<!--
  ****************************************************************************
  * Copyright 2018-2024,2025 Thomas E. Dickey                                *
  * Copyright 2002-2015,2017 Free Software Foundation, Inc.                  *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
  * "Software"), to deal in the Software without restriction, including      *
  * without limitation the rights to use, copy, modify, merge, publish,      *
  * distribute, distribute with modifications, sublicense, and/or sell       *
  * copies of the Software, and to permit persons to whom the Software is    *
  * furnished to do so, subject to the following conditions:                 *
  *                                                                          *
  * The above copyright notice and this permission notice shall be included  *
  * in all copies or substantial portions of the Software.                   *
  *                                                                          *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  *                                                                          *
  * Except as contained in this notice, the name(s) of the above copyright   *
  * holders shall not be used in advertising or otherwise to promote the     *
  * sale, use or other dealings in this Software without prior written       *
  * authorization.                                                           *
  ****************************************************************************
  * @Id: curs_bkgrnd.3x,v 1.58 2025/02/15 18:40:23 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>curs_bkgrnd 3x 2025-02-15 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">

</HEAD>
<BODY>
<H1 class="no-header">curs_bkgrnd 3x 2025-02-15 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>                  Library calls                 <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>




</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
       <STRONG>bkgrnd</STRONG>,   <STRONG>wbkgrnd</STRONG>,   <STRONG>bkgrndset</STRONG>,  <STRONG>wbkgrndset</STRONG>,  <STRONG>getbkgrnd</STRONG>,  <STRONG>wgetbkgrnd</STRONG>  -
       manipulate background of a <EM>curses</EM> window of wide characters


</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>

       <STRONG>int</STRONG> <STRONG>bkgrnd(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>wbkgrnd(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>

       <STRONG>void</STRONG> <STRONG>bkgrndset(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
       <STRONG>void</STRONG> <STRONG>wbkgrndset(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>

       <STRONG>int</STRONG> <STRONG>getbkgrnd(cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>wgetbkgrnd(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>


</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
       Every <EM>curses</EM>  window  has  a  <EM>background</EM>  <EM>character</EM>  property:  in  the
       library's   wide  configuration,  it  is  a  <EM>curses</EM>  complex  character
       (<EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>) that combines  a  set  of  attributes  (and,  if  colors  are
       enabled,  a color pair identifier) with a character code.  When erasing
       (parts of)  a  window,  <EM>curses</EM>  replaces  the  erased  cells  with  the
       background character.

       <EM>curses</EM>  also uses the background character when writing characters to a
       populated window.

       <STRONG>o</STRONG>   The attribute part of the background character  combines  with  all
           non-blank  character  cells  in  the  window,  as  populated by the
           <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> and <STRONG><A HREF="curs_ins_wch.3x.html">wins_wch(3x)</A></STRONG> families of functions (and those that
           call them).

       <STRONG>o</STRONG>   Both  the character code and attributes of the background character
           combine with blank character cells in the window.

       The background character's set of attributes becomes a property of  the
       character cell and move with it through any scrolling and insert/delete
       line/character operations.  To the  extent  possible  on  the  terminal
       type, <EM>curses</EM> displays the attributes of the background character as the
       graphic rendition of a character cell on the display.


</PRE><H3><a name="h3-bkgrnd_wbkgrnd">bkgrnd, wbkgrnd</a></H3><PRE>
       <STRONG>bkgrnd</STRONG> and <STRONG>wbkgrnd</STRONG>  set  the  background  property  of  <STRONG>stdscr</STRONG>  or  the
       specified window and then apply this setting to every character cell in
       that window.

       <STRONG>o</STRONG>   The rendition of every character in the window changes to  the  new
           background rendition.

       <STRONG>o</STRONG>   Wherever the former background character appears, it changes to the
           new background character.

       <EM>ncurses</EM> updates the rendition of each character cell by  comparing  the
       character, non-color attributes, and color pair selection.  The library
       applies to following procedure to each cell in the window,  whether  or
       not it is blank.

       <STRONG>o</STRONG>   <EM>ncurses</EM>  first  compares  the  cell's  character  to the previously
           specified background character; if they match, <EM>ncurses</EM>  writes  the
           new background character to the cell.

       <STRONG>o</STRONG>   <EM>ncurses</EM> then checks whether the cell uses color; that is, its color
           pair value is nonzero.  If not, it simply replaces  the  attributes
           and  color  pair  in  the  cell  with those from the new background
           character.

       <STRONG>o</STRONG>   If the cell uses color, and its background color  matches  that  of
           the  current window background, <EM>ncurses</EM> removes attributes that may
           have come from the current background and adds those from  the  new
           background.   It  finishes  by setting the cell's background to use
           the new window background color.

       <STRONG>o</STRONG>   If the cell uses color, and its background  color  does  not  match
           that  of  the  current  window background, <EM>ncurses</EM> updates only the
           non-color attributes, first removing those that may have come  from
           the  current  background,  and  then adding attributes from the new
           background.

       If the new background's character is non-spacing,  <EM>ncurses</EM>  reuses  the
       old background character, except for one special case: <EM>ncurses</EM> treats a
       background character code of zero (0) as a space.

       If the terminal does not support  color,  or  if  color  has  not  been
       initialized  with  <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG>,  <EM>ncurses</EM> ignores the new background
       character's color pair selection.


</PRE><H3><a name="h3-bkgrndset_wbkgrndset">bkgrndset, wbkgrndset</a></H3><PRE>
       <STRONG>bkgrndset</STRONG> and <STRONG>wbkgrndset</STRONG> manipulate the background  of  the  applicable
       window,  without updating the character cells as <STRONG>bkgrnd</STRONG> and <STRONG>wbkgrnd</STRONG> do;
       only future writes reflect the updated background.


</PRE><H3><a name="h3-getbkgrnd_wgetbkgrnd">getbkgrnd, wgetbkgrnd</a></H3><PRE>
       <STRONG>getbkgrnd</STRONG> and <STRONG>wgetbkgrnd</STRONG> respectively  obtain  <STRONG>stdscr</STRONG>'s  or  the  given
       window's background character, attributes, and color pair, and store it
       in their <EM>wch</EM> argument.


</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
       <STRONG>bkgrndset</STRONG> and <STRONG>wbkgrndset</STRONG> do not return a value.

       Functions returning an <EM>int</EM> return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
       In <EM>ncurses</EM>, failure occurs if

       <STRONG>o</STRONG>   the <EM>curses</EM> screen has not been initialized,

       <STRONG>o</STRONG>   <EM>win</EM> is <EM>NULL</EM>, or

       <STRONG>o</STRONG>   <EM>wch</EM> is <EM>NULL</EM>.


</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
       <STRONG>bkgrnd</STRONG>, <STRONG>bkgrndset</STRONG>, and <STRONG>getbkgrnd</STRONG> may be implemented as macros.

       Unlike  their  counterparts  in  the non-wide configuration of <EM>ncurses</EM>,
       <STRONG>getbkgrnd</STRONG> and <STRONG>wgetbkgrnd</STRONG> store the background character in a modifiable
       <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> parameter, rather than supplying it as the return value.


</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
       X/Open Curses Issue 4 describes these functions.  It specifies no error
       conditions for them.

       X/Open Curses does not provide details of how the rendition is updated.
       <EM>ncurses</EM>  follows  the approach used in SVr4 <EM>curses</EM>'s non-wide functions
       for manipulating the window background.


</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
       X/Open Curses Issue 4 (1995) initially specified these functions.


</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
       <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> describes the corresponding  functions  in  the  non-wide
       configuration of <EM>ncurses</EM>.

       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>



ncurses 6.5                       2025-02-15                   <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-bkgrnd_wbkgrnd">bkgrnd, wbkgrnd</a></li>
<li><a href="#h3-bkgrndset_wbkgrndset">bkgrndset, wbkgrndset</a></li>
<li><a href="#h3-getbkgrnd_wgetbkgrnd">getbkgrnd, wgetbkgrnd</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
